Greenbone Community Containers¶

Running the Greenbone Community Edition from containers requires knowledge about:

Using a terminal
Using docker
Running services via docker compose

Additionally, a basic knowledge about the architecture of the Greenbone Community Edition is required to understand the setup.

Note

This guide is intended for users who want to test the newest features and/or want to get familiar with the Greenbone Community Edition. It is not intended for production setups.

Currently the docs support the following distributions

Debian stable (bookworm)
Ubuntu 22.04 LTS
Fedora 35 and 36
CentOS 9 Stream

Most likely, other Debian derivatives like Mint and Kali will also work with only minor adjustments required.

Introduction¶

This document provides a guide for running the Greenbone Community Edition from pre-built container images using Docker. It consists of a distributed service architecture, where each service is run in a dedicated container. The orchestration of these services is done via a docker-compose file.

With the Greenbone Community Containers, it is possible to scan your local network independent of the underlying operating system, installed software and tool chains.

Hardware Requirements¶

Minimal:

CPU Cores: 2
Random-Access Memory: 4GB
Hard Disk: 20GB free

Recommended:

CPU Cores: 4
Random-Access Memory: 8GB
Hard Disk: 60GB free

Prerequisites¶

Note

Please follow the guide step by step. Later steps might require settings or output of a previous command.

The command sudo is used for executing commands that require privileged access on the system.

Install dependencies¶

There are a few dependencies required for the following steps like curl, which is required for downloading files from this guide.

Install ca-certificates, curl and gnupg Debian/Ubuntu packages¶

sudo apt install ca-certificates curl gnupg

Install ca-certificates, curl and gnupg Fedora/CentOS packages¶

sudo dnf install ca-certificates curl gnupg

Installing Docker¶

docker is required for running the services within containers. Docker can be installed by running the following commands (taken from the Docker Engine install guide):

Uninstall conflicting Debian packages¶

for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt remove $pkg; done

Set up the Docker repository¶

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

Install Docker Debian packages¶

sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Uninstall conflicting Ubuntu packages¶

for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt remove $pkg; done

Set up the Docker repository¶

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

Install Docker Ubuntu packages¶

sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Uninstall conflicting Fedora packages¶

sudo dnf remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-selinux docker-engine-selinux docker-engine

Install docker Fedora package¶

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Start Docker¶

sudo systemctl start docker

Uninstall conflicting CentOS packages¶

sudo dnf remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-selinux docker-engine-selinux docker-engine

Install Docker CentOS package¶

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Start Docker¶

sudo systemctl start docker

Setup¶

To allow the current user to run docker and therefore start the containers, they must be added to the docker user group. To make the group change effective, either logout and login again or use su.

Add current user to docker group and apply group changes for the current shell environment¶

sudo usermod -aG docker $USER && su $USER

For downloading the Greenbone Community Edition docker compose file, a destination directory should be created.

Create download directory¶

export DOWNLOAD_DIR=$HOME/greenbone-community-container && mkdir -p $DOWNLOAD_DIR

Docker Compose File¶

To run the Greenbone Community Edition with containers, the following compose file should be used:

Docker Compose File¶

services:
  vulnerability-tests:
    image: registry.community.greenbone.net/community/vulnerability-tests
    environment:
      STORAGE_PATH: /var/lib/openvas/22.04/vt-data/nasl
    volumes:
      - vt_data_vol:/mnt

  notus-data:
    image: registry.community.greenbone.net/community/notus-data
    volumes:
      - notus_data_vol:/mnt

  scap-data:
    image: registry.community.greenbone.net/community/scap-data
    volumes:
      - scap_data_vol:/mnt

  cert-bund-data:
    image: registry.community.greenbone.net/community/cert-bund-data
    volumes:
      - cert_data_vol:/mnt

  dfn-cert-data:
    image: registry.community.greenbone.net/community/dfn-cert-data
    volumes:
      - cert_data_vol:/mnt
    depends_on:
      - cert-bund-data

  data-objects:
    image: registry.community.greenbone.net/community/data-objects
    volumes:
      - data_objects_vol:/mnt

  report-formats:
    image: registry.community.greenbone.net/community/report-formats
    volumes:
      - data_objects_vol:/mnt
    depends_on:
      - data-objects

  gpg-data:
    image: registry.community.greenbone.net/community/gpg-data
    volumes:
      - gpg_data_vol:/mnt

  redis-server:
    image: registry.community.greenbone.net/community/redis-server
    restart: on-failure
    volumes:
      - redis_socket_vol:/run/redis/

  pg-gvm:
    image: registry.community.greenbone.net/community/pg-gvm:stable
    restart: on-failure
    volumes:
      - psql_data_vol:/var/lib/postgresql
      - psql_socket_vol:/var/run/postgresql

  gvmd:
    image: registry.community.greenbone.net/community/gvmd:stable
    restart: on-failure
    volumes:
      - gvmd_data_vol:/var/lib/gvm
      - scap_data_vol:/var/lib/gvm/scap-data/
      - cert_data_vol:/var/lib/gvm/cert-data
      - data_objects_vol:/var/lib/gvm/data-objects/gvmd
      - vt_data_vol:/var/lib/openvas/plugins
      - psql_data_vol:/var/lib/postgresql
      - gvmd_socket_vol:/run/gvmd
      - ospd_openvas_socket_vol:/run/ospd
      - psql_socket_vol:/var/run/postgresql
    depends_on:
      pg-gvm:
        condition: service_started
      scap-data:
        condition: service_completed_successfully
      cert-bund-data:
        condition: service_completed_successfully
      dfn-cert-data:
        condition: service_completed_successfully
      data-objects:
        condition: service_completed_successfully
      report-formats:
        condition: service_completed_successfully

  gsa:
    image: registry.community.greenbone.net/community/gsa:stable
    restart: on-failure
    ports:
      - 127.0.0.1:9392:80
    volumes:
      - gvmd_socket_vol:/run/gvmd
    depends_on:
      - gvmd
  # Sets log level of openvas to the set LOG_LEVEL within the env
  # and changes log output to /var/log/openvas instead /var/log/gvm
  # to reduce likelyhood of unwanted log interferences
  configure-openvas:
    image: registry.community.greenbone.net/community/openvas-scanner:stable
    volumes:
      - openvas_data_vol:/mnt
      - openvas_log_data_vol:/var/log/openvas
    command:
      - /bin/sh
      - -c
      - |
        printf "table_driven_lsc = yes\nopenvasd_server = http://openvasd:80\n" > /mnt/openvas.conf
        sed "s/127/128/" /etc/openvas/openvas_log.conf | sed 's/gvm/openvas/' > /mnt/openvas_log.conf
        chmod 644 /mnt/openvas.conf
        chmod 644 /mnt/openvas_log.conf
        touch /var/log/openvas/openvas.log
        chmod 666 /var/log/openvas/openvas.log

  # shows logs of openvas
  openvas:
    image: registry.community.greenbone.net/community/openvas-scanner:stable
    restart: on-failure
    volumes:
      - openvas_data_vol:/etc/openvas
      - openvas_log_data_vol:/var/log/openvas
    command:
      - /bin/sh
      - -c
      - |
        cat /etc/openvas/openvas.conf
        tail -f /var/log/openvas/openvas.log
    depends_on:
      configure-openvas:
        condition: service_completed_successfully

  openvasd:
    image: registry.community.greenbone.net/community/openvas-scanner:stable
    restart: on-failure
    environment:
      # `service_notus` is set to disable everything but notus,
      # if you want to utilize openvasd directly removed `OPENVASD_MODE`
      OPENVASD_MODE: service_notus
      GNUPGHOME: /etc/openvas/gnupg
      LISTENING: 0.0.0.0:80
    volumes:
      - openvas_data_vol:/etc/openvas
      - openvas_log_data_vol:/var/log/openvas
      - gpg_data_vol:/etc/openvas/gnupg
      - notus_data_vol:/var/lib/notus
    # enable port forwarding when you want to use the http api from your host machine
    # ports:
    #   - 127.0.0.1:3000:80
    depends_on:
      vulnerability-tests:
        condition: service_completed_successfully
      configure-openvas:
        condition: service_completed_successfully
      gpg-data:
        condition: service_completed_successfully
    networks:
      default:
        aliases:
          - openvasd

  ospd-openvas:
    image: registry.community.greenbone.net/community/ospd-openvas:stable
    restart: on-failure
    hostname: ospd-openvas.local
    cap_add:
      - NET_ADMIN # for capturing packages in promiscuous mode
      - NET_RAW # for raw sockets e.g. used for the boreas alive detection
    security_opt:
      - seccomp=unconfined
      - apparmor=unconfined
    command:
      [
        "ospd-openvas",
        "-f",
        "--config",
        "/etc/gvm/ospd-openvas.conf",
        "--notus-feed-dir",
        "/var/lib/notus/advisories",
        "-m",
        "666"
      ]
    volumes:
      - gpg_data_vol:/etc/openvas/gnupg
      - vt_data_vol:/var/lib/openvas/plugins
      - notus_data_vol:/var/lib/notus
      - ospd_openvas_socket_vol:/run/ospd
      - redis_socket_vol:/run/redis/
      - openvas_data_vol:/etc/openvas/
      - openvas_log_data_vol:/var/log/openvas
    depends_on:
      redis-server:
        condition: service_started
      gpg-data:
        condition: service_completed_successfully
      vulnerability-tests:
        condition: service_completed_successfully
      configure-openvas:
        condition: service_completed_successfully

  gvm-tools:
    image: registry.community.greenbone.net/community/gvm-tools
    volumes:
      - gvmd_socket_vol:/run/gvmd
      - ospd_openvas_socket_vol:/run/ospd
    depends_on:
      - gvmd
      - ospd-openvas

volumes:
  gpg_data_vol:
  scap_data_vol:
  cert_data_vol:
  data_objects_vol:
  gvmd_data_vol:
  psql_data_vol:
  vt_data_vol:
  notus_data_vol:
  psql_socket_vol:
  gvmd_socket_vol:
  ospd_openvas_socket_vol:
  redis_socket_vol:
  openvas_data_vol:
  openvas_log_data_vol:

Download¶

It is possible to just copy and paste the docker compose file. Alternatively, it can be downloaded with the following command directly:

Downloading docker-compose file¶

cd $DOWNLOAD_DIR && curl -f -L https://greenbone.github.io/docs/latest/_static/docker-compose-22.4.yml -o docker-compose.yml

Description¶

The following table describes the provided containers of the docker compose file and their services in detail.

Container	Service	Description
redis-server	Redis Server	A redis server with an adjusted config. Used to store VT data and scan results by the scanner.
pg-gvm	postgresql	A PostgreSQL database cluster setup for use with gvmd. The actual data is stored in the `psql_data_vol` volume.
gvmd	gvmd	A container for gvmd that uses unix sockets in volumes to communicate with the PostgreSQL database and ospd-openvas scanner. The downloaded feed data is stored in the `gvmd_data_vol` volume. To verify the feed data, the GPG keyring from the `gpg_data_vol` is used.
gsa	gsad	A container running the gsad web server for providing the web application GSA. The web interface is available at localhost on port 9392. For communication with gvmd, a unix socket in a volume is used.
ospd-openvas	ospd-openvas	A container providing the vulnerability scanner. The VT data from the feed is stored in the `vt_data_vol` volume. To verify the feed data, the GPG keyring from the `gpg_data_vol` is used. The connection to the redis server is established via a unix socket in a volume.
gvm-tools		A container providing the gvm-tools CLI to query and control gvmd and ospd-openvas.
gpg-data		A container that copies a GPG keyring with Greenbone’s public signing keys into the `gpg_data_vol` volume on startup. It exits afterwards.
vulnerability-tests		A container that copies vulnerability tests (VTs) into the `vt_data_vol` volume on startup. Shows the license and exits afterwards.
notus-data		A container that copies vulnerability information for notus-scanner into the `notus_data_vol` volume on startup. Shows the license and exits afterwards.
scap-data		A container that copies CVE and CPE data into the `scap_data_vol` volume on startup. Shows the license and exits afterwards.
cert-bund-data		A container that copies CERT-Bund data into the `cert_data_vol` volume on startup. Shows the license and exits afterwards.
dfn-cert-data		A container that copies DFN-CERT data into the `cert_data_vol` volume on startup. Shows the license and exits afterwards.
data-objects		A container that copies scan configs, compliance policies and port lists into the `data_objects_vol` volume on startup. Shows the license and exits afterwards.
report-formats		A container that copies report formats into the `data_objects_vol` volume on startup. Shows the license and exits afterwards.
configure-openvas		A container for setting up the configuration for OpenVAS Scanner
openvas		A container that shows the logs of OpenVAS Scanner
openvasd	openvasd	A container for openvasd. It is providing notus, a static vulnerability engine, functionality.

Starting the Greenbone Community Containers¶

Using the docker compose file, the container images can be downloaded (pulled) and the containers can be started in the background.

Downloading the Greenbone Community Containers¶

docker compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition pull

Starting the Greenbone Community Containers¶

docker compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition up -d

To get a continuous stream of the log output of all services, run the following command:

Show log messages of all services from the running containers¶

docker compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition logs -f

The log stream can be stopped by pressing Ctrl-C.

Setting up an Admin User¶

Warning

By default, a user admin with the password admin is created. This is insecure and it is highly recommended to set a new password.

To update the administrator user with a password of your choice instead of the generated password, the following command can be used:

Updating password of administrator user¶

docker compose -f $DOWNLOAD_DIR/docker-compose.yml -p greenbone-community-edition \
    exec -u gvmd gvmd gvmd --user=admin --new-password='<password>'

Note

Please be aware if your password includes special characters like $ it needs to be quoted in single quotes.

Starting the Vulnerability Management¶

After the services have started and all feed data has been loaded, the Greenbone Security Assistant web interface – GSA – can be opened in the browser.

Opening Greenbone Security Assistant in the browser¶

xdg-open "http://127.0.0.1:9392" 2>/dev/null >/dev/null &

The browser will show the login page of GSA and after using the credentials created before, it is possible to start with vulnerability scanning.

Launching Greenbone Security Assistant for the first time — Greenbone Security Assistant after logging in for the first time¶

Setup and Start Script¶

Note

Please remember to follow the instructions described in the Prerequisites first.

As a quick solution we provide all the commands above in a single script. This script can be downloaded with the following command directly:

Downloading setup and start script to the current working dir¶

curl -f -O https://greenbone.github.io/docs/latest/_static/setup-and-start-greenbone-community-edition.sh && chmod u+x setup-and-start-greenbone-community-edition.sh

To execute the script following command needs to be run

Run setup and start script¶

./setup-and-start-greenbone-community-edition.sh